// 版权所有2009 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

// 解析“zoneinfo”时区文件。
// 这是在OS X、Linux、BSD、Sun和其他系统上使用的一种相当标准的文件格式。
// 参见tzfile（5），https:
// 和ftp:

package time

import (
	"errors"
	"runtime"
	"syscall"
)

// time/tzdata包调用registerLoadFromEmbeddedTZData，
// （如果已导入）。
func registerLoadFromEmbeddedTZData(f func(string) (string, error)) {
	loadFromEmbeddedTZData = f
}

// loadFromEmbeddedTZData用于从二进制文件本身中嵌入的tzdata信息加载特定的tzdata文件
// 。
// 这是在导入time/tzdata包时设置的，
// 通过registerLoadFromEmbeddedTzdata。
var loadFromEmbeddedTZData func(zipname string) (string, error)

// maxFileSize是readFile允许读取的最大文件大小。
// 作为参考，区域信息。Go分发的zip大约为350KB，
// 所以10MB是多余的。
const maxFileSize = 10 << 20

type fileSizeError string

func (f fileSizeError) Error() string {
	return "time: file " + string(f) + " is too large"
}

// io的副本。查找*常量以避免导入“io”：
const (
	seekStart   = 0
	seekCurrent = 1
	seekEnd     = 2
)

// 将简单I/O接口导入二进制数据块。
type dataIO struct {
	p     []byte
	error bool
}

func (d *dataIO) read(n int) []byte {
	if len(d.p) < n {
		d.p = nil
		d.error = true
		return nil
	}
	p := d.p[0:n]
	d.p = d.p[n:]
	return p
}

func (d *dataIO) big4() (n uint32, ok bool) {
	p := d.read(4)
	if len(p) < 4 {
		d.error = true
		return 0, false
	}
	return uint32(p[3]) | uint32(p[2])<<8 | uint32(p[1])<<16 | uint32(p[0])<<24, true
}

func (d *dataIO) big8() (n uint64, ok bool) {
	n1, ok1 := d.big4()
	n2, ok2 := d.big4()
	if !ok1 || !ok2 {
		d.error = true
		return 0, false
	}
	return (uint64(n1) << 32) | uint64(n2), true
}

func (d *dataIO) byte() (n byte, ok bool) {
	p := d.read(1)
	if len(p) < 1 {
		d.error = true
		return 0, false
	}
	return p[0], true
}

// read返回对缓冲区中数据的读取。
func (d *dataIO) rest() []byte {
	r := d.p
	d.p = nil
	return r
}

// 通过在第一个NUL处停止生成字符串
func byteString(p []byte) string {
	for i := 0; i < len(p); i++ {
		if p[i] == 0 {
			return string(p[0:i])
		}
	}
	return string(p)
}

var badData = errors.New("malformed time zone information")

// LoadLocationFromTZData返回一个名为
// 的位置，该位置由IANA时区数据库格式化数据初始化。
// 数据的格式应为标准IANA时区文件
// （例如，Unix系统上的/etc/localtime的内容）。
func LoadLocationFromTZData(name string, data []byte) (*Location, error) {
	d := dataIO{data, false}

	// 4字节魔法“TZif”
	if magic := d.read(4); string(magic) != "TZif" {
		return nil, badData
	}

	// 1字节版本，然后是15字节的填充
	var version int
	var p []byte
	if p = d.read(16); len(p) != 16 {
		return nil, badData
	} else {
		switch p[0] {
		case 0:
			version = 1
		case '2':
			version = 2
		case '3':
			version = 3
		default:
			return nil, badData
		}
	}

	// 六个大端32位整数：
	// UTC/本地指示器
	// 标准/墙壁指示器
	// 闰秒数
	// 转换次数
	// 本地时区数
	// 时区字符数abbrev字符串
	const (
		NUTCLocal = iota
		NStdWall
		NLeap
		NTime
		NZone
		NChar
	)
	var n [6]int
	for i := 0; i < 6; i++ {
		nn, ok := d.big4()
		if !ok {
			return nil, badData
		}
		if uint32(int(nn)) != nn {
			return nil, badData
		}
		n[i] = int(nn)
	}

	// 如果我们有版本2或3，那么数据首先以32位格式写入
	// 然后以64位格式再次写入。
	// 跳过32位格式，读取64位格式，因为它可以描述更广泛的日期范围。

	is64 := false
	if version > 1 {
		// 跳过32位数据。
		skip := n[NTime]*4 +
			n[NTime] +
			n[NZone]*6 +
			n[NChar] +
			n[NLeap]*8 +
			n[NStdWall] +
			n[NUTCLocal]
		// 跳过我们刚刚读到的版本2标题。
		skip += 4 + 16
		d.read(skip)

		is64 = true

		// 再次读取计数，它们可能不同。
		for i := 0; i < 6; i++ {
			nn, ok := d.big4()
			if !ok {
				return nil, badData
			}
			if uint32(int(nn)) != nn {
				return nil, badData
			}
			n[i] = int(nn)
		}
	}

	size := 4
	if is64 {
		size = 8
	}

	// 转换时间。
	txtimes := dataIO{d.read(n[NTime] * size), false}

	// 过渡时间的时区索引。
	txzones := d.read(n[NTime])

	// 区域信息结构
	zonedata := dataIO{d.read(n[NZone] * 6), false}

	// 时区缩写。
	abbrev := d.read(n[NChar])

	// 闰秒时间对
	d.read(n[NLeap] * (size + 4))

	// 是否将与本地时间类型
	// 关联的发送时间指定为标准时间或墙时间。
	isstd := d.read(n[NStdWall])

	// 是否将与本地时间类型
	// 关联的发送时间指定为UTC或本地时间。
	isutc := d.read(n[NUTCLocal])

	if d.error { // 数据用完了
		return nil, badData
	}

	var extend string
	rest := d.rest()
	if len(rest) > 2 && rest[0] == '\n' && rest[len(rest)-1] == '\n' {
		extend = string(rest[1 : len(rest)-1])
	}

	// 现在我们可以建立一个有用的数据结构。
	// 首先是区域信息。
	// utcoff[4]isdst[1]名称索引[1]
	nzone := n[NZone]
	if nzone == 0 {
		// 拒绝不带区域的tzdata文件。它们没有什么用处。
		// 这也避免了以后我们添加并使用假转换时的恐慌（golang.org/issue/29437）。
		return nil, badData
	}
	zones := make([]zone, nzone)
	for i := range zones {
		var ok bool
		var n uint32
		if n, ok = zonedata.big4(); !ok {
			return nil, badData
		}
		if uint32(int(n)) != n {
			return nil, badData
		}
		zones[i].offset = int(int32(n))
		var b byte
		if b, ok = zonedata.byte(); !ok {
			return nil, badData
		}
		zones[i].isDST = b != 0
		if b, ok = zonedata.byte(); !ok || int(b) >= len(abbrev) {
			return nil, badData
		}
		zones[i].name = byteString(abbrev[b:])
		if runtime.GOOS == "aix" && len(name) > 8 && (name[:8] == "Etc/GMT+" || name[:8] == "Etc/GMT-") {
			// AIX 7.2 TL 0在Etc中有一个错误，
			// GMT+1将返回GMT-1，而不是GMT+1或-01。
			if name != "Etc/GMT+0" {
				// GMT+0正常
				zones[i].name = name[4:]
			}
		}
	}

	// 现在是过渡时间信息。
	tx := make([]zoneTrans, n[NTime])
	for i := range tx {
		var n int64
		if !is64 {
			if n4, ok := txtimes.big4(); !ok {
				return nil, badData
			} else {
				n = int64(int32(n4))
			}
		} else {
			if n8, ok := txtimes.big8(); !ok {
				return nil, badData
			} else {
				n = int64(n8)
			}
		}
		tx[i].when = n
		if int(txzones[i]) >= len(zones) {
			return nil, badData
		}
		tx[i].index = txzones[i]
		if i < len(isstd) {
			tx[i].isstd = isstd[i] != 0
		}
		if i < len(isutc) {
			tx[i].isutc = isutc[i] != 0
		}
	}

	if len(tx) == 0 {
		// 构建假过渡以覆盖所有时间。
		// 这种情况发生在“Etc/GMT0”等固定位置。
		tx = append(tx, zoneTrans{when: alpha, index: 0})
	}

	// 致力于成功。
	l := &Location{zone: zones, tx: tx, name: name, extend: extend}

	// 在缓存中填入有关当前的信息，因为这将是最常见的查找。
	sec, _, _ := now()
	for i := range tx {
		if tx[i].when <= sec && (i+1 == len(tx) || sec < tx[i+1].when) {
			l.cacheStart = tx[i].when
			l.cacheEnd = omega
			l.cacheZone = &l.zone[tx[i].index]
			if i+1 < len(tx) {
				l.cacheEnd = tx[i+1].when
			} else if l.extend != "" {
				// 如果我们在已知区域转换的末尾，请尝试扩展字符串。
				if name, offset, estart, eend, isDST, ok := tzset(l.extend, l.cacheEnd, sec); ok {
					l.cacheStart = estart
					l.cacheEnd = eend
					// 如果可能的话，找到tzset返回的区域以避免分配。
					if zoneIdx := findZone(l.zone, name, offset, isDST); zoneIdx != -1 {
						l.cacheZone = &l.zone[zoneIdx]
					} else {
						l.cacheZone = &zone{
							name:   name,
							offset: offset,
							isDST:  isDST,
						}
					}
				}
			}
			break
		}
	}

	return l, nil
}

func findZone(zones []zone, name string, offset int, isDST bool) int {
	for i, z := range zones {
		if z.name == name && z.offset == offset && z.isDST == isDST {
			return i
		}
	}
	return -1
}

// loadTzinfoFromDirOrZip返回文件名为
// in dir的内容。dir可以是未压缩的zip文件，也可以是目录。
func loadTzinfoFromDirOrZip(dir, name string) ([]byte, error) {
	if len(dir) > 4 && dir[len(dir)-4:] == ".zip" {
		return loadTzinfoFromZip(dir, name)
	}
	if dir != "" {
		name = dir + "/" + name
	}
	return readFile(name)
}

// 有500多个zoneinfo文件。我们没有单独分发它们，而是将它们放在一个未压缩的zip文件中。
// 使用这种方式，zip文件格式可以作为单个小文件的通用可读容器。我们选择zip而不是tar因为zip文件有一个连续的目录，使得单个文件的查找速度更快，而且每个文件的开销也更大

// get4返回b中的小端32位值。
func get4(b []byte) int {
	if len(b) < 4 {
		return 0
	}
	return int(b[0]) | int(b[1])<<8 | int(b[2])<<16 | int(b[3])<<24
}

// get2返回b中的小端16位值。
func get2(b []byte) int {
	if len(b) < 2 {
		return 0
	}
	return int(b[0]) | int(b[1])<<8
}

// loadTzinfoFromZip返回给定未压缩zip文件中名为
// 的文件内容。
func loadTzinfoFromZip(zipfile, name string) ([]byte, error) {
	fd, err := open(zipfile)
	if err != nil {
		return nil, err
	}
	defer closefd(fd)

	const (
		zecheader = 0x06054b50
		zcheader  = 0x02014b50
		ztailsize = 22

		zheadersize = 30
		zheader     = 0x04034b50
	)

	buf := make([]byte, ztailsize)
	if err := preadn(fd, buf, -ztailsize); err != nil || get4(buf) != zecheader {
		return nil, errors.New("corrupt zip file " + zipfile)
	}
	n := get2(buf[10:])
	size := get4(buf[12:])
	off := get4(buf[16:])

	buf = make([]byte, size)
	if err := preadn(fd, buf, off); err != nil {
		return nil, errors.New("corrupt zip file " + zipfile)
	}

	for i := 0; i < n; i++ {
		// zip条目布局：
		// 0 magic[4]
		// 4 madevers[1]
		// 5 madeos[1]
		// 6 extvers[1]
		// 24 uncsize[4]
		// 28 namelen[2]
		// 30 xlen[2]
		// 32 fclen[2]
		// 34 disknum[2]
		// 
		if get4(buf) != zcheader {
			break
		}
		meth := get2(buf[10:])
		size := get4(buf[24:])
		namelen := get2(buf[28:])
		xlen := get2(buf[30:])
		fclen := get2(buf[32:])
		off := get4(buf[42:])
		zname := buf[46 : 46+namelen]
		buf = buf[46+namelen+xlen+fclen:]
		if string(zname) != name {
			continue
		}
		if meth != 0 {
			return nil, errors.New("unsupported compression for " + name + " in " + zipfile)
		}

		// zip-per-file头布局：
		// 0 magic[4]
		// 4 extvers[1]
		// 5 exters[1]
		// 6标志[2]
		// 8方法[2]
		// 26 namelen[2]
		// 28 xlen[2]
		// 30 name[namelen]
		// 30+namelen+xlen-文件数据
		// 
		buf = make([]byte, zheadersize+namelen)
		if err := preadn(fd, buf, off); err != nil ||
			get4(buf) != zheader ||
			get2(buf[8:]) != meth ||
			get2(buf[26:]) != namelen ||
			string(buf[30:30+namelen]) != name {
			return nil, errors.New("corrupt zip file " + zipfile)
		}
		xlen = get2(buf[28:])

		buf = make([]byte, size)
		if err := preadn(fd, buf, off+30+namelen+xlen); err != nil {
			return nil, errors.New("corrupt zip file " + zipfile)
		}

		return buf, nil
	}

	return nil, syscall.ENOENT
}

// loadTzinfoFromTzdata返回时区的时区信息
// ，来自tzdata数据库文件，因为它们通常是在android上找到的
// 文件。
var loadTzinfoFromTzdata func(file, name string) ([]byte, error)

// loadTzinfo返回时区的时区信息
// 使用给定的名称，从给定的源返回。源可以是包含此类目录内容的
// 时区数据库目录、tzdata数据库文件或未压缩的
// zip文件。
func loadTzinfo(name string, source string) ([]byte, error) {
	if len(source) >= 6 && source[len(source)-6:] == "tzdata" {
		return loadTzinfoFromTzdata(source, name)
	}
	return loadTzinfoFromDirOrZip(source, name)
}

// loadLocation从指定的源之一返回具有给定名称的位置。有关支持的源的列表，请参阅loadTzinfo。
// 成功加载并解析的与给定名称匹配的第一个时区数据将作为位置返回。
func loadLocation(name string, sources []string) (z *Location, firstErr error) {
	for _, source := range sources {
		var zoneData, err = loadTzinfo(name, source)
		if err == nil {
			if z, err = LoadLocationFromTZData(name, zoneData); err == nil {
				return z, nil
			}
		}
		if firstErr == nil && err != syscall.ENOENT {
			firstErr = err
		}
	}
	if loadFromEmbeddedTZData != nil {
		zonedata, err := loadFromEmbeddedTZData(name)
		if err == nil {
			if z, err = LoadLocationFromTZData(name, []byte(zonedata)); err == nil {
				return z, nil
			}
		}
		if firstErr == nil && err != syscall.ENOENT {
			firstErr = err
		}
	}
	if firstErr != nil {
		return nil, firstErr
	}
	return nil, errors.New("unknown time zone " + name)
}

// readFile读取并返回指定文件的内容。
// 这是一个简单的操作系统实现。ReadFile，在这里重新实现
// 以避免依赖io/ioutil或os。
// 如果名称超过maxFileSize字节，则返回一个错误。
func readFile(name string) ([]byte, error) {
	f, err := open(name)
	if err != nil {
		return nil, err
	}
	defer closefd(f)
	var (
		buf [4096]byte
		ret []byte
		n   int
	)
	for {
		n, err = read(f, buf[:])
		if n > 0 {
			ret = append(ret, buf[:n]...)
		}
		if n == 0 || err != nil {
			break
		}
		if len(ret) > maxFileSize {
			return nil, fileSizeError(name)
		}
	}
	return ret, err
}
